Developer CD Series 1993 March: Other People's Memory

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Technical Documentation / Sample Code / DTS.Lib & Samples / DTS.Lib / =DTS.framework.fns next >

Wrap

Text File | 1992-10-22 | 46.4 KB | 786 lines | [TEXT/MPS ]

/************** AEConnect.c **************/ void InitConnectAppleEvents(void); /* This function initializes the connect AppleEvents stuff. It needs to be ** called so that DTS.framework applications can connect with other applications ** specific to a targeted window. */ OSErr SendConnect(FileRecHndl frHndl, char *theLocNBPType); /* This is the function that is called to establish a connection to another ** DTS.framework-based application. The "other" DTS.framework application is probably ** the same application on another machine. This code does a bit more than simply ** connecting to another application. It targets a specific window within that application. ** It doesn’t just target zone/machine/application, which is the granularity that AppleEvents ** gives you. It also passes back and forth some information that is kind of a pain to get, ** but is nice to have. One such piece of information is the user name. This needs to be ** sent. It can’t be determined from the message from an AppleEvent. The sender sends ** the user name, and the receiver returns the remote user name. The user name is ** placed in the document record for the window to be used if you wish. */ WindowPtr GetAEWindow(long windID_0, long windID_1); /* This function is called to determine which window, if any, is the designated ** target window. The window ID’s are determined when the connection is established. */ /************** AERequired.c **************/ void InitRequiredAppleEvents(void); /* Intializes AppleEvent dispatcher table for the required events. It also ** determines if the machine is PPCBrowser and AppleEvent capable. If so, ** the booleans gHasAppleEvents and gHasPPCToolbox are set true. This function ** must be the first AppleEvents initialization DTS.framework function called, as the ** other functions depend on the booleans being set correctly. */ /************** AEUtils.c **************/ void DoHighLevelEvent(EventRecord *event); /* This function simply calls AEProcessAppleEvent and reports any errors. */ OSErr GetTargetInfo(AEAddressDesc targetDesc, StringPtr zone, StringPtr machine, StringPtr application); /* This function returns the zone, machine, and application name for the ** indicated target descriptor. */ OSErr MakeTarget(AEAddressDesc *target, Boolean sendDirect, short replyMode, Str255 prompt, Str255 applListLabel, PPCFilterProcPtr portFilter, char *theLocNBPType); /* Creates a TargetID. If sendDirect is TRUE, the target is specified by setting ** a ProcessSerialNumber to kCurrentProcess. This has the advantage of sending ** the message directly to ourselves, bypassing ePPC and gaining about a 10-15x ** speed improvement. If sendDirect is FALSE, we see if we have the ** PPCToolBox. If not, then we are forced to do a direct send. If we do have ** the PPCToolbox, then we call PPCBrowser. We then look at the reply, and ** factor in the mode we are going to use in AESend. If that mode is ** kAEWaitReply and the user selected us as the target, we have to turn that ** into a direct send. This is because the AppleEvent Manager will otherwise ** post the event as a high-level event. However, we are busy waiting for a ** reply, not looking for events, so we’ll hang. We avoid this by forcing a ** direct send. */ Boolean MissedAnyParameters(AppleEvent *message); /* Used to check for any unread required parameters. Returns true if we ** missed at least one. */ void NotifyCancel(void); /* Use this function to cancel a notification. Simply call it for a resume. It checks if ** there is a notification to cancel, and if there is one, it cancels it. */ void NotifyUser(void); /* When an Apple Event is received, call this. If the application isn’t the front-most ** application, a notification is posted. */ /************** CtlHandler.c **************/ short CNum2Ctl(WindowPtr window, short ctlNum, ControlHandle *ctl); /* This function converts a control number to a control handle. The function ** simply walks the window’s control list counting down until it has reached ** the right control number. It also returns the number of controls traversed. ** While often this will be the same as the control number passed in, if the ** number passed in is greater than the number of controls in the list, then ** the number returned is the number of controls in the list. */ short Ctl2CNum(ControlHandle ctl); /* This function converts a control handle to a control number. The function ** simply walks the window’s control list and counts how many controls it ** has to traverse before finding the target control. The smallest control ** number that can be returned is 1. This makes control numbers similar to ** dialog item numbers. */ void DoCtlActivate(WindowPtr window); /* This function reactivates the last active TextEdit or List control for ** the indicated window. */ void GetCheckBoxValues(WindowPtr window, Boolean checkBoxVal[]); /* This function returns all the checkBox values into the designated array. ** The function walks the control list, and when it finds a checkBox control, ** it gets the control value and places it in the next position in the array. ** This allows a single call to retrieve all the checkBox values at once. */ short GetRadioButtonChoice(WindowPtr window, short famNum); /* This function returns which radio button is selected for a particular ** family of radio buttons. It finds the radio button of the target family ** with the lowest control number and it subtracts this number from the ** selected radio button of the same family. This gives a relative radio ** button number as a return result. This way the position of the family ** of radio buttons can change in the window and the return result is the ** same. The family number is stored in the control’s refCon field. */ short IsCtlEvent(WindowPtr window, EventRecord *event, ControlHandle *ctl, short *action); /* This function currently handles events for TextEdit, List, and button ** controls in a window. It also handles the window scrollbars and scrolling ** of the window. If the event is handled, it returns non-zero. See the ** document “=Using CtlHandler.c” for more information. */ /************** File.c **************/ OSErr DefaultInitDocument(FileRecHndl frHndl, short version, short numUndos, short numSaveUndos); /* This function does the standard document initialization. The standard document uses ** the hierarchical document package TreeObj. Read the TreeObj documentation for ** more information. */ OSErr DisposeDocument(FileRecHndl frHndl); /* This function is automatically called by such functions as DisposeOneWindow. It ** calls the designated free document procedure, which by default is FreeDocument. ** The free document procedure is responsible for disposing of any and all handles ** that were created by the init document procedure. */ OSErr NewDocument(FileRecHndl *returnHndl, OSType sftype, Boolean incTitleNum); /* This function needs to be called by the application at appropriate times. It ** calls the designated init document procedure, which by default is InitDocument. ** The init document procedure is responsible for creating any and all initial ** handles for the document. New documents will be created with a default title. This ** title is created by appending a number to the corresponding STR# individual string. ** The STR# resource ID #259 holds the default text for the window titles. Which string ** number is determined by the OSType array gTypeList. gTypeList contains all of the ** file types that can be opened by the application. The list is walked, and the location ** in the gTypeList array that holds the correct file type is used as an index into ** the STR# resource. If the file type isn’t found in the list, then the first string ** in the STR# resource is used. ** The next greatest integer is appended to the end of the individual string selected ** for the document. If incTitleNum is true, then the global integer is first incremented ** prior to appending the number. ** If you want to create a document with the title found in the 'WIND' resource, first ** call NewDocument(). After you have the frHndl for the document, set the file name ** in the (*frHndl)->fileState.fss.name field to an empty string. When the window is ** opened for this document, if this name is an empty string, it titles the window ** according to what is found in the 'WIND' resource for that window. If this field is ** not an empty string, then the 'WIND' title is overridden, and the file name is used. */ OSErr OpenDocument(FileRecHndl *result, FSSpecPtr fileToOpen, char permission); /* This function does the human-interface thing for opening a document. It ** also calls NewDocument() to initialize a document. To actually read in ** the data, OpenDocument() calls the designated read document procedure, which by ** default is ReadDocument(). The read document procedure is responsible for reading ** the document data into ram in association with the FileRecHndl created by ** NewDocument(). */ OSErr SaveDocument(FileRecHndl frHndl, WindowPtr window, short saveMode); /* This function does the human-interface thing for saving a document. To ** actually write out the data, SaveDocument calls the designated write document ** procedure, which by default is WriteDocument. The write document procedure is ** responsible for writing the document data to the designated file. */ void ConvertOldToNewSFReply(SFReply *oldReply, StandardFileReply *newReply); /* When running on a pre-7.0 system, SFGetFile or SFPutFile is called. Then ** ConvertOldToNewSFReply is called to convert the reply record to the new ** format. This allows the rest of the application to use only a single ** record format. */ Boolean DisplayGetFile(StandardFileReply *reply); /* Simple routine to display a list of files with our file type. */ Boolean DisplayPutFile(StandardFileReply *reply); /* Displays the StandardFile PutFile dialog box. Fills out the passed reply ** record, and returns the sfGood field as a result. */ OSErr UseDocResFile(FileRecHndl frHndl, short *oldRes, char perm); /* Use the resource fork for the designated document file. This function ** also returns the old CurResFile, so you can set it back when you are done. ** Simply call this function, whether or not you have a resource fork. If ** there isn’t a resource fork, then one will be created. If there is one, ** but it isn’t open yet, it will be opened. If it is already opened, it ** sets it as the current resource fork. What more do you want? */ OSErr CloseDocResFile(FileRecHndl frHndl); /* If there is a resource fork open for this document, this closes it. */ long GetModNum(void); /* Get the modification number for the document. TreeObj automatically increments this. */ Boolean GetDocDirty(FileRecHndl frHndl); /* Get the dirty state of the document. */ Boolean GetWindowDirty(WindowPtr window); /* Given a window, return the dirty state of the associated document. */ void SetDocDirty(FileRecHndl frHndl); /* Set the document dirty. */ void SetWindowDirty(WindowPtr window); /* Given a window, set the associated document as dirty. */ OSErr FSpSetWD(FSSpec fss, short *wd, Boolean *created, short *oldWDRefNum); /* Given an FSSpec, set the working directory. Working directories are a bad ** idea, but there are instances where they have to be used. Some 3rd-party ** utilities don’t accept an FSSpec, and want just the file name. In these ** instances you could generate a full pathname, but that isn’t so wonderful, ** either. This function is here for cases where you are already having ** difficulties. It is not here as the definitive solution. ** If you are going to use this function, it should be used as a one-shot deal. ** First, call FSpSetWD to temporarily set a working directory. Then go about ** your business right away. After you have finished with the working directory, ** which should be immediately after a create or open, call FSpResetWD, which ** gets rid of the wworking directory that you created. Do not leave working ** directories around, as there is a limitied number that the system can handle. */ OSErr FSpResetWD(short wd, Boolean created, short oldWDRefNum); /* Use this function to get rid of a working directory that was created via ** FSpSetWD. Call this as soon as possible after creatig a working directory. */ /************** Init.c **************/ void Initialize(short moreMasters, long minHeap, long minSpace, ProcPtr init1, ProcPtr init2); /* Given minHeap and minSpace values, get stuff going. Also, we are passed ** in two procedure pointers. If these are not nil, they are called at ** intermediate points during the initialization process. The first proc ** is called after the Utilities.c standard initialization is complete. The ** second proc is called very near the end of the initialization, but just ** prior to the menus being initialized. */ void StartDocuments(void); /* This is startup code that shouldn’t have to change. */ /************** Print.c **************/ OSErr PrintDocument(FileRecHndl frHndl, Boolean jobDlg, Boolean firstJob); void DonePrinting(void); OSErr PresentStyleDialog(FileRecHndl frHndl); /* These three functions are the generic print support for DTS.framework. ** You shouldn’t have to make any changes to these functions. PrintDocument calls ** the designated image procedure. The default procedure is ImageDocument. You can ** change it if you wish. ImageDocument images the document to either the window ** or to the printer. The port is already set when ImageDocument is called to either ** the window’s port or the printer port. The global variable gPrintPage is set ** so that you can determine if you are imaging for the window or for the printer. ** If gPrintPage is 0 then you are imaging for the window. If gPrintPage is non-0, ** then that is the page you are imaging to the printer. If you are printing, and ** have imaged the final page, your imaging code should set gPrintPage to 0. This ** tells PrintDocument that you have done the final page. The reason for this ** is that the user could request to print pages 4 to 27, and you only have 14 pages ** in the document. The imaging procedure "knows" how many pages the document ** has, and by having the imaging procedure return that it is finished, we eliminate ** the need for the generic print code to have to know how many pages are in the ** document. Once your application has finished printing, it should call ** DonePrinting. This frees up a THPrint handle that is used for job merging. If ** you don’t call DonePrinting after printing, you get a memory leak. */ /************** TreeObj.c **************/ /* This is a complete package unto itself. See the accompanying read-me for this guy, ** called "=Using TreeObj.c". Also, check out the TreeObj.h header file. Each function ** has a brief description of its use. For an example of TreeObj usage, see DTS.Draw. */ /************** Window.c **************/ OSErr DoNewWindow(FileRecHndl frHndl, WindowPtr *retWindow, WindowPtr relatedWindow, WindowPtr behind); /* This function is called by the application at appropriate times to give a document ** a window. To create a document window, first a document is created by the application ** via NewDocument or OpenDocument. If this succeeds then the application needs to create ** a window for the document. To do this, the application calls DoNewWindow. DoNewWindow ** calls the content initialization procedure, which by default is InitContent. ** If you want a different content initialization procedure, replace the ** default procedure pointer initContentProc with your own. Normally however, ** you will just place your own content initialization procedure in the ** function InitContent. It is possible though that your ** application has more than one document type and window type. If this ** is the case, then you may very well want an alternate content ** initialization procedure. If you do, you will want to replace the ** default procedure pointer after the NewDocument or OpenDocument ** call and before the call to DoNewWindow. (You may place the code for ** replacing the content initialization procedure and imaging procedure ** in the function InitDocument. The defaults are already established ** at that point. You would just replace them with the alternates. */ void NewWindowTitle(WindowPtr window, char *altTitle); /* Call this function if you want to change the title of the window. ** If you pass in nil, the window title will be gotten from the FSSpec of the document. ** If you pass in an alternate title in altTitle, that will be used instead ** of the document name. */ Boolean DisposeAllWindows(void); Boolean DisposeOneWindow(WindowPtr window, short saveMode); /* These functions do exactly as you would expect. The saveMode indicates ** whether the window is being closed due to a close request, or due to the ** application being quit. */ WindowPtr SetFilePort(FileRecHndl frHndl); /* This function sets the current port for the designated file. It also returns ** the old port so that the port can be restored, if so desired. */ void DoResizeWindow(WindowPtr window, short oldh, short oldv); /* This function is called when a window is resized. This function needs to ** know the old size of the window. The new size is determined by the ** dimensions of the window that was resized. It moves and resizes the ** document scrollbars and growIcon (if any) to reflect the new size of ** the window. It then calls the procedure stored in the procPtr field ** resizeContentProc, in case there is additional sizing necessary for the window. ** The default resizeContentProc is ResizeContent. If you wish an alternate ** resizeContentProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. */ void DoUpdateSeparate(WindowPtr window, RgnHandle *contRgn, RgnHandle *frameRgn); /* This function separates the update region into two portions. One portion is ** the frame area, which consists of document scrollbars and growIcon (if any), plus ** an optional application-defined frame area. The other portion is the rest of the ** window content that needs updating. This separation is so that the document ** scrollbars can be updated first, and then this area can be clipped out of the rest ** of the updating so that the window content doesn’t draw over the document scrollbars ** and growIcon. The clipping is managed with just the visRgn. This frees up the clipRgn ** for application specific clipping. */ void BeginContent(WindowPtr window); /* This function clips out the document scrollbars and growIcon from the updatable area. ** It also sets the origin of the port to the current document scrollbar values. ** BeginContent must be balanced by a call to EndContent. BeginContent calls BeginUpdate, ** and BeginUpdate calls can’t be nested. Due to this, BeginContent has a usage counter, ** which prevents nested calls to BeginUpdate. BeginContent clips out the document ** scrollbar and growIcon area without involving the clipRgn so that the application is ** free to use the clipRgn as it sees fit. The only caveat is that you can not modify the ** updateRgn between the BeginContent and EndContent calls, as anything contributed to the ** updateRgn between these calls will be lost. If you need to do this, accumulate the areas ** in a separate region, call EndContent, and then call InvalRgn. */ void EndContent(WindowPtr window); /* Calls to BeginContent must be balanced. They also don’t nest. EndContent undoes the ** clipping of the frame area that BeginContent invoked. */ void AdjustScrollBars(WindowPtr window); /* You call this function whenever you change the amount that the arrows scroll ** the document, or whenever the document changes size. These values are first ** stored in the document’s fileState structure. Once the new values are in ** place, call AdjustScrollBars to affect all related changes. */ void GetContentOrigin(WindowPtr window, Point *contOrg); /* This function returns the origin of the content of the window. The value is ** gotten from the current value of the document scrollbars. If a scrollbar ** is missing, the control value for that scrollbar is assumed to be 0. Note that ** if you have sidebars in your document, the origin value has the sidebar value ** subtracted. For example: You have a top sidebar of 32 pixels, and the vertical ** scrollbar has a control value of 0. This will return you a vertical origin of -32. */ void SetContentOrigin(WindowPtr window, short newh, short newv); /* This function allows you to change the value of the document scrollbars, ** and by doing this, the document is scrolled to reflect the change, and ** an update event is generated for the document scroll. Note that if you are ** using sidebars, you will have to subtract the value of the sidebar to get ** the expected results (see GetContentOrigin). */ void GetContentRect(WindowPtr window, Rect *contRct); /* This function returns a rectangle that represents the content area of the ** window less the scrollbar and sidebar areas. */ void SetDocSize(FileRecHndl frHndl, short hSize, short vSize); /* This function sets the document size to the new designated size. It also ** makes appropriate adjustments to the scrollbars to reflect the new size. */ void SetSidebarSize(FileRecHndl frHndl, short newLeft, short newTop); /* This function is used to set the size of the sidebars. This is particularly ** useful for being able to show and hide a tool palette, or if you are using ** OCE and want to show a mailer at the top of your window. The sidebar value ** should initially be set in File2.c, along with other document initialization. ** If you wish to change only one of the two sidebar sizes, send in a value of ** kwNoChange for the one that is not to change. */ void SetScrollIndentSize(FileRecHndl frHndl, short newh, short newv); /* This function is used to set the size of the scrollbar indention. The scrollbar ** indentnion allows you to put status information or document display related ** tool icons in line with the scrollbar. They are considered part of the frame, ** as document scrollbars, the grow icon, and sidebars are. The scrollbar indent value ** should initially be set in File2.c, in the same fashion as sidebar values are set. ** If you wish to change only one of the two scrollbar indent, send in a value of ** kwNoChange for the one that is not to change. */ FileRecHndl GetNextDocument(WindowPtr window, OSType sftype); /* This function returns the file reference for the next application window ** of the designated kind. If the window paramater is passed in as nil, it ** finds the top-most window. If the window parameter is passed in as non-nil, ** it returns the next window. If there is no next window found, it returns ** nil. The sftype parameter restricts the finding of a window to a particular ** type. If 0 is passed in for sftype, then any application window will match. */ WindowPtr GetNextWindow(WindowPtr window, OSType sftype); /* This function behaves the same as GetNextDocument, but returns a window pointer ** instead of a file reference. */ WindowPtr GetPreviousWindow(WindowPtr window); /* Returns the window in front of the window passed in. If there is no window ** in front, it returns -1, not nil. -1 is typically used to indicate the front ** of the window list, whereas nil is used to indicate the back. This is done to ** stay consistent with the expectations of the toolbox. */ void DoZoomWindow(WindowPtr window, EventRecord *event, short zoomDir); /* This function handles zooming of the document window. It zooms it to the ** current monitor, up to the size of the document data. */ RgnHandle DoCalcFrameRgn(WindowPtr window); /* This function calculates the region that encompasses the frame area of the document. ** The frame area consists of the document scrollbars, growIcon, sidebars, and an ** optional application-defined frame area. The region is generated in global coordinates. ** Since the frame region may encompass more than the DTS.framework-supported scrollbars and ** growIcon, a procedure is first called to see if there is anything additional ** in the frame region. The field calcFrameRgnProc holds the procedure pointer ** that contributes any extra to the frame region. This function is passed an ** empty region. If there is no additional contribution to the frame region, ** then the region should be left empty. Once this procedure is returned from, ** the remaining frame portion is added to this region. The remaining portion ** would consist of DTS.framework document scrollbars and a growIcon, if there ** are any for this window. The field calcFrameRgnProc is initialized to the ** default value CalcFrameRgn. If you wish an alternate drawFrameProc, then you ** can replace the default in the function InitDocument, as the default is ** already established at this point. */ RgnHandle DoCalcScrollRgn(WindowPtr window); /* This function calculates the region that encompasses the document scrollbars ** and growIcon (if any). The region is generated in global coordinates. */ void DoContentClick(WindowPtr window, EventRecord *event, Boolean firstClick); /* This function is called whenever the content portion of a window is clicked in. ** It simply calls the procedure pointer stored in the field contentClickProc. ** The field contentClickProc is initialized to ContentClick. If you wish ** an alternate contentClickProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. The ** boolean firstClick is true if you chose this window to handle first clicks, and ** if the click is actually a first click in the window. A first click means that ** the window content was clicked on, but the window was not the front window. The ** window has already been brought to the front, but you may wish the click to also ** be handled as a content click. */ void DoDragWindow(WindowPtr window, EventRecord *event, Rect bounds); /* This function is used to drag a window. We can’t use the toolbox function DragWindow, ** as the DTS.framework supports palettes. Since we are supporting palettes, we have to ** be able to drag a window that isn’t the front, and bring it to the front of windows ** of its kind. There is no way to coerce DragWindow to do this. */ void DoDrawFrame(WindowPtr window); /* This function may be called when an update event occurs for the window. ** If the update region intersects the frame region (calculated by DoCalcFrameRgn), ** then a frame update occurs and this function is called. It redraws the ** document scrollbars and growIcon (if any) and then calls the procedure stored ** in the field drawFrameProc, which has a default value of DrawFrame. If you wish ** an alternate drawFrameProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. */ OSErr DoFreeDocument(FileRecHndl frHndl); /* This is called to generically call the document’s freeing procedure. This document ** is being disposed of, and any custom memory usage needs to be deallocated. The ** frHndl itself will be disposed of, but any handle references that it contains ** need to be freed within the document’s freeing procedure. The default freeing ** procedure is called FreeDocument(). */ OSErr DoFreeWindow(FileRecHndl frHndl, WindowPtr window); /* This is called to generically call the document’s window freeing procedure. ** The window is going to be disposed of, and there may be related tasks to disposing ** of the window. A document may have related windows or views. This is where you ** would dispose of the related windows. The default window freeing procedure is called ** FreeWindow(). */ OSErr DoImageDocument(FileRecHndl frHndl); /* This function is called whenever the content portion of a window needs to be ** updated or printed. It simply calls the procedure pointer stored in the field ** imageProc. The field imageProc is initialized to ImageDocument. If you wish ** an alternate imageProc, then you can replace the default in the function ** InitDocument, as the default is already established at this point. */ OSErr DoInitContent(FileRecHndl frHndl, WindowPtr window); /* The window has been created, and is about to be displayed. At this time, this ** function is called. It generically calls the window content initialization procedure ** indicated within the frHndl. The default window content initialization procedure is ** called InitContent(). */ void DoKeyDown(EventRecord *event); /* DoKeyDown is first called by the application. If the key is a menu key, the ** application function DoMenuCommand() is called. If the key isn’t a menu ** key, DoKeyDown starts walking through the window list, giving each window an ** opportunity to handle the key. Windows can handle it, eat it, or pass the key ** through to the next window. ** It gives each window a chance to handle the key by calling the key handling procedure ** stored in the frHndl. The default procedure is called KeyDown(). Here are the ** rules for the window key handling procedure: ** ** 1) If it handles the key, it returns true. This completes the key handling. ** 2) If it doesn’t handle the key, it returns false. However, there are two ** situations for not handling the key: ** a) The window wants windows behind it to try handling the key. ** b) The window wants nobody else to look at the key. ** This is what the boolean passThrough is for. If the procedure wishes the next ** window to have a look at the key, it should set the boolean passThrough to true. ** passThrough is already initialized to false prior to calling the procedure, which ** is the common case, so the window key handling procedure only has to worry about ** setting it true. ** ** If the window never processes keys and always passes them through to the next window, ** the contentKeyProc field in the frHndl should be set to nil. This will indicate to ** DoKeyDown() that all keys should be passed through this window. DTS.Draw has ** such a window. The palette window doesn’t accept keys. They are passed through ** to document windows that are behind the palette. */ void DoMouseDown(EventRecord *event); /* Call this whenever a mouse down event occurs in the application. Everything is ** handled. Here’s what DoMouseDown() may do, and what it depends on: ** It handles: ** inContent ** inDrag ** inGoAway ** inGrow ** inMenuBar ** inSysWindow ** inZoomIn ** inZoomOut ** ** inContent: ** a) If the window clicked on is a DA window, then bring the window to the front. ** b) If the window is not the top-most of its kind (palette,dialog,document), then ** it is made the top-most of its kind. If the window has the kwDoFirstClick bit ** set, then DoContentClick is called, indicating that it is a first click. ** ** inDrag: ** The window is dragged. When released, if the command key was not held down at the ** time of the click, the window is made the top-most window of its kind. ** ** inGoAway: ** The go-away is tracked. If the document is dirty, then the user is asked if the ** document should first be saved. The user can save, discard, or cancel. All cases ** are handled. ** ** inGrow: ** The window is grown. Scrollbar adjustments are handled as they are in the 7.0 finder. ** ** inMenuBar: ** MenuSelect() is called, then the application function DoMenuCommand() is called ** with the result of MenuSelect(). ** ** inSysWindow: ** SystemClick() is called. ** ** inZoomIn: ** inZoomOut: ** The window is grown, according to the human-interface guidelines for zooming. ** The window is zoomed on the monitor that contains most of the window. The zoom ** size is limited by the document size. All of these details are handled. */ OSErr DefaultFreeDocument(FileRecHndl frHndl); /* This procedure frees up the memory used by the document and undo hierarchies. ** If you are using the hierarchical document package, call this to free up all ** memory allocated for the document. */ OSErr DoReadDocument(FileRecHndl frHndl); /* DoReadDocument() calls the specific read document procedure for the document. ** The specific procedure is stored in the frHndl field readDocumentProc. The ** default value for readDocumentProc is ReadDocument(). It is the responsibility ** of the readDocument procedure to call the readDocumentHeader procedure. This is ** done by calling DoReadDocumentHeader() from within the readDocumentProc. */ OSErr DoReadDocumentHeader(FileRecHndl frHndl); /* DoReadDocumentHeader() calls the specific read document header procedure for the ** document. The specific procedure is stored in the frHndl field readDocumentHeaderProc. ** The default value for readDocumentHeaderProc is DefaultReadDocumentHeader(). */ OSErr DefaultReadDocument(FileRecHndl frHndl); /* You can call this from in your readDocumentProc. DefaultReadDocument() first calls ** DoReadDocumentHeader() for the document. It then reads in a hierarchical document ** by calling the TreeObj function ReadTree(). If this behavior isn’t what you want, ** you will need to write your own code to read in the file. You can find an example ** custom read document in the sample application DTS.Chat. */ OSErr DefaultReadDocumentHeader(FileRecHndl frHndl); /* This function reads in the default header for a file. The header information is ** described by the structure DocHeaderInfo. The typedef for this structure is in the ** file DTS.Lib.h. This block of header information is saved at the beginning of the file. ** It is written to the data fork. If you want the header information saved in the resource ** fork, you will have to have a custom readDocumentHeaderProc and writeDocumentHeaderProc. ** You can then simply read and write using the resource fork, instead of the data fork, as ** the defaults do. */ OSErr DefaultReadDocumentFixup(FileRecHndl frHndl); /* If you are using the TreeObj hierarchical document package, some document fixup needs ** to be done after reading in the document. Handle references were converted to ID’s ** when the document was saved. These need to be converted back to handle references. ** Calling this function takes care of this. DTS.Draw uses the hierarchical document ** package. Take a look at its ReadDocument() function. */ OSErr DoWriteDocument(FileRecHndl frHndl); /* DoWriteDocument() calls the specific write document procedure for the document. ** The specific procedure is stored in the frHndl field writeDocumentProc. The ** default value for writeDocumentProc is WriteDocument(). It is the responsibility ** of the writeDocument procedure to call the writeDocumentHeader procedure. This is ** done by calling DoWriteDocumentHeader() from within the writeDocumentProc. */ OSErr DoWriteDocumentHeader(FileRecHndl frHndl); /* DoWriteDocumentHeader() calls the specific write document header procedure for the ** document. The specific procedure is stored in the frHndl field writeDocumentHeaderProc. ** The default value for writeDocumentHeaderProc is DefaultWriteDocumentHeader(). */ OSErr DefaultWriteDocument(FileRecHndl frHndl); /* You can call this from in your writeDocumentProc. DefaultWriteDocument() first calls ** DoWriteDocumentHeader() for the document. It then writes out a hierarchical document ** by calling the TreeObj function WriteTree(). If this behavior isn’t what you want, ** you will need to write your own code to write in the file. You can find an example ** custom write document in the sample application DTS.Chat. */ OSErr DefaultWriteDocumentHeader(FileRecHndl frHndl); /* This function writes out the default header for a file. The header information is ** described by the structure DocHeaderInfo. The typedef for this structure is in the ** file DTS.Lib.h. This block of header information is saved at the beginning of the file. ** It is written to the data fork. If you want the header information saved in the resource ** fork, you will have to have a custom readDocumentHeaderProc and writeDocumentHeaderProc. ** You can then simply read and write using the resource fork, instead of the data fork, as ** the defaults do. */ void DoResizeContent(WindowPtr window, short oldh, short oldv); /* This function is called when a window has been resized. It is possible that window ** contents have to be adjusted to match the new window size. DoResizeContent() handles ** this. DoResizeContent() uses a procedure stored in the frHndl field resizeContentProc. ** If resizeContentProc is not nil, then the procedure is called. The default value for ** resizeContentProc is ResizeContent(). */ void DoScrollFrame(WindowPtr window, long dx, long dy); /* Some applications may need to scroll the "frame" of the document along with the document ** contents. This is common for applications with rulers, or other similar sidebar items. ** DoScrollFrame is called when document scrolling has occured. DoScrollFrame() uses a ** procedure stored in the frHndl field scrollFrameProc. If scrollFrameProc is not nil, ** then the procedure is called. The default value for scrollFrameProc is ScrollFrame(). */ void DoUndoFixup(FileRecHndl frHndl, Point contOrg, Boolean afterUndo); /* This function is called by the hierarchical document package in response to an undo/redo ** operation. It is called prior to any undo information being applied to the document so ** that you can prepare the document for an undo. It is also called after all undo tasks ** are performed on the document. This last call is a chance for any additional cleanup ** that might have to occur. Commonly this second call is used to reimage the document to ** show the document undone/redone. DoUndoFixup() doesn’t actually do the work, as it doesn’t ** know what kind of document it was called for. It simply looks in the frHndl at the field ** undoFixupProc. If undoFixupProc is not nil, then the procedure is called. The default ** value for undoFixupProc is UndoFixup(). */ WindowPtr GetOldLocWindow(short id, Ptr storage, Boolean vis, WindowPtr relWindow, WindowPtr behind, Boolean inColor, Rect sizeInfo, long refCon); /* This function is used in conjunction with the window attribute kwOpenAtOldLoc. If the ** window is to be opened at the old location, then GetOldLocWindow() is used, instead of ** the Utilities.c function GetStaggeredWindow(). */ void CleanSendBehind(WindowPtr window, WindowPtr afterWindow); /* This function is exactly what it would seem by the name. SendBehind() has some problems ** in that it causes too much repainting of windows. This function allows you to change the ** layer of a window very cleanly. It also calls HiliteWindows(), which walks the window ** list and adjusts window hilighting for the various types of windows. The top-most of a ** type is hilited, and all other windows of that type are unhilited. */ void CleanSendInFront(WindowPtr window, WindowPtr beforeWindow); /* Again, this is exactly what it would seem. See CleanSendBehind() for more information. */ void HiliteWindows(void); /* This function is called to adjust the hilites of all windows. Since DTS.framework ** supports palettes, there is possibly more than one hilited window. The window manager ** doesn’t want to play this game, so certain additional functions had to be written. ** Basically, if you are using palettes, don’t make any window manager calls that change ** window hiliting. Use CleanSendBehind() and CleanSendInFront(). These take care of ** window shuffling correctly. Of course, there are calls you can’t avoid, such as ** closing a window. If you do these operations directly, call HiliteWindows() afterwards. */ void UnhiliteWindows(void); /* This is called to unhilite all windows. DTS.framework allows for multiple hilited windows. ** All of them have to be unhilited prior to bringing up a modal dialog or alert. Call this ** to unhilite all windows, do the modal dialog or alert, and then call HiliteWindows() to ** set the hiliting back to normal. */ void DoUpdate(WindowPtr window); /* This is called when an update event is received for a window. First, the ** updateRgn is separated into two parts. Part 1 holds the window frame area, ** if any. This is the area that might hold the scrollbars, grow icon, and ** any other application-specific frame parts. This is drawn first. Once ** this is done, the remainder of the updateRgn is drawn. This allows us to ** handle all of the frame clipping without using the clipRgn. By freeing up ** the clipRgn, we allow the application to use it without having to share. */ void DoSetCursor(Cursor *cursor); /* Call this function to correctly set the cursor and to inform DTS.framework that ** you have specifically set the cursor. This is used when you temporarily want to ** set the cursor, such as just before a slow operation. For a slow operation, you ** may want to put up the wait cursor. Use DoSetCursor() for this, and then when the ** operation is over and program control returns to the main event loop, the cursor ** will be recalculated to the current cursor for the mouse position. */ CursPtr DoSetResCursor(short crsrID); /* This function serves the same purpose as DoSetCursor, except that you pass in ** a resID, instead of a cursor pointer. The resource is loaded, the cursor is then ** copied into permanent memory, and then DoSetCursor is called with a pointer to ** the cursor image. */ void DoWindowCursor(void); /* Call this function to calculate what the cursor should be for various windows. ** The result of this function is to set the cursor based on the current mouse position. ** In addition to setting the cursor, the cursor region is calculated. The cursor ** region is kept in the global variable gCursorRgn. ** This function walks the window list, and for each document window, it calls the ** window’s cursor handling procedure. The cursor handling procedure is stored in ** the frHndl field windowCursorProc. ** Here are the rules for cursor and gCursorRgn determination: ** ** 1) See if the mouse position is currently inside the gCursorRgn. If so, leave. ** 2) Since the mouse position is outside the current gCursorRgn, we need to recalculate ** the cursor. Set the gCursorRgn to wide-open. From now on, we will eliminate areas ** from gCursorRgn that don’t apply to the new mouse location and new cursor. ** 3) For each visible window (starting with the front window): ** a) If the windowCursorProc is nil and the mouse position is over the structure region ** of the window, set the cursor to an arrow and intersect the gCursorRgn with the ** structure region of the window. This limits the cursor to the area of the window ** that is visible. ** b) If the windowCursorProc is nil and the mouse position is outside the structure region ** of the window, diff out the structure region from gCursorRgn and proceed to the next ** visible window in the window list. ** c) If the windowCursorProc is not nil, call the procedure. Note that the procedure is ** called whether or not the mouse location is over the window. This is to allow the ** procedure to determine if it should be the last window checked. ** The proc’s job is as follows: ** 1) If the cursor is over a position that is determined by the window, then ** the proc removes other areas from gCursorRgn. Note that it should not ** simply set the area to what it "thinks" is the correct area. This window ** may not be the front-most. Other windows will have already been subtracted ** from gCursorRgn. The resultant gCursorRgn is the correct cursor area, ** and should be passed to WaitNextEvent calls in the application. Also, ** the cursor should be set to the correct cursor, of course. ** You should also return true, as the cursor has been determined. ** The rule of thumb for what you should do to the gCursorRgn is that you should ** calculate the cursor region as if the window was the top window. Once this ** is done, intersect the gCursorRgn with this region. The result should be ** stored in gCursorRgn. ** Since you determined a cursor and gCursorRgn in this case, you should return ** true. Returning true indicates to DoWindowCursor() that the cursor has been ** determined, and that it should stop processing windows. ** 2) If the cursor is not over a position for this window, then you should ** return. You will either pass back true or false. If you don’t wish ** windows behind this window to have a shot at cursor determination, then ** return true. This states that the cursor is "determined". It is, in the ** sense that no further determination will occur. If you return false, then ** other windows get a shot at determining the cursor. If there are no other windows, ** then the cursor is set to an arrow, and gCursorRgn is set to the area that is outside ** all windows for the application. ** (Common case:) If you don’t want windows behind this one to determine the cursor: ** a) Set the cursor to an arrow. Since you are outside this window, the cursor ** should be an arrow. The cursor may be over the desktop or menubar, or some ** other window that isn’t the top-most window. All of these cases should have ** an arrow cursor. Also, you need to diff out the window’s structure region from ** gCursorRgn. By diffing it out, you will get mouse-moved events when the ** cursor is moved back over this window. ** b) Return true. This tells DoWindowCursor() that the cursor has been determined. ** (Uncommon case:) If you want windows behind this one to possibly determine the cursor: ** Return false. That’s it. DTS.framework will automatically remove the structure ** region for this window from gCursorRgn if you return false. If you return false, ** DTS.framework proceeds to the next window, if there is one. If there are no more ** windows behind this one, then DTS.framework sets the cursor to an arrow, and ** the resultant gCursorRgn will have all of the structure regions for the windows ** removed from it. */ WindowPtr FrontWindowOfType(short wkind); /* Since DTS.framework supports three distinct categories of windows (document/palette/dialog), ** it is often necessary to get the front-most window of a certain type. Use this function ** to accomplish this. Basically, this takes the place of FrontWindow() if you have more ** than one category of window in your application. */